Skip to content

EAI-7199: Add CI guard pinning the first-party crate dependency graph - #422

Merged
jussielo-amd merged 3 commits into
mainfrom
worktree-eai-7199-crate-edge-guard
Sep 22, 2026
Merged

jussielo-amd merged 3 commits into
mainfrom
worktree-eai-7199-crate-edge-guard

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Sep 22, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Adds cargo xtask check-crate-edges: pins the allowlist of permitted first-party crate dependency edges (derived from cargo metadata --no-deps) and fails with a specific rule-violation message when an edge outside it appears, or when an allowlist entry has no matching edge left in the graph (a removed dependency whose entry wasn't cleaned up).
  • Wires the new check into the clippy CI job, right after the existing cargo xtask manifest --check step, under the same rust-changes gate.
  • Covers the three layering invariants from §1+§2: polish, harden, invariant re-proofs + ROADMAP update #38 that were previously enforced by nothing and documented nowhere: rocmd must never depend on rocm (the reverse, rocm -> rocmd, is the allowed/expected direction), rocm-dash-core must stay a pure leaf crate, and rocm-dash-tui must not depend on rocm-core.
  • Dev-dependency edges are collected but never checked against the allowlist, since Cargo already permits those to cycle (e.g. rocm-dash-daemon's test-only dev-dep on rocm-core).

Why: this is Phase 0 of the EAI-7768 modularization epic — sequenced first because it protects the whole refactor and lands with an empty exception list (zero current violations on main). A literal cycle check would be a no-op (Cargo's resolver already rejects those); the value is entirely in the allowlist, which catches any new first-party coupling, not just the three named invariants — bidirectionally, so both a new undeclared edge and a stale entry left behind by a removed dependency get caught.

Risk: low. Pure CI-tooling addition — no production code paths touched, no new external dependencies (reuses xtask's existing serde/anyhow), and the check currently passes on main with zero grandfathered entries.

Non-goals: documenting the invariants in AGENTS.md/README (flagged separately via a comment on EAI-8045, which already touches those files for the related module-per-subsystem convention) and a local pre-commit hook for the guard (CI-only for now, matching the ticket's scope).

Test plan

  • cargo test -p xtask — 147 passed (9 new tests in crate_edges, including a fixture-based test that a deliberately-injected disallowed edge fails with the correct message, and a real-workspace regression test).
  • cargo run -p xtask -- check-crate-edges exits 0 against the current workspace.
  • cargo clippy -p xtask --all-targets -- -D warnings and cargo fmt --all -- --check both clean.
  • cargo xtask manifest --check unaffected (no new external dependency introduced).
  • Manually verified the allowlist matches cargo metadata's actual first-party edge graph exactly (25 edges, no gaps or stale entries), and that removing an entry from the allowlist causes the check to fail with the expected message before restoring it.

N/A: not a bug fix, so the expectations.toml checklist item doesn't apply.

rocm-cli's workspace has layering invariants (rocmd must never depend
on rocm; rocm-dash-core stays pure; rocm-dash-tui has no rocm-core
edge) that were previously enforced by nothing. Add `cargo xtask
check-crate-edges`, which pins the allowed first-party dependency
edges via `cargo metadata` and fails CI on anything outside that
allowlist, naming the offending edge and the rule it breaks.

Wired into the existing `clippy` CI job right after the MANIFEST.md
check. Dev-dependency edges are exempt since Cargo already permits
those to cycle.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The guard does not detect stale allowlist entries, allowing removed dependencies to be reintroduced without review.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
What changed in this PR

Adds a CI guard for approved first-party Rust crate dependency edges.

Changes:

  • Adds check-crate-edges to xtask.
  • Defines and tests dependency-layer invariants.
  • Runs the guard in the CI clippy job.
File Description
xtask/​src/​main.rs Registers the new command.
xtask/​src/​crate_edges.rs Implements the dependency-edge guard and tests.
.github/​workflows/​ci.yml Adds the guard to CI.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread xtask/src/crate_edges.rs Resolved
check-crate-edges only checked that every real edge is in ALLOWLIST,
never the reverse. A dependency removed from a crate's Cargo.toml
left its allowlist entry behind, silently permitting the same edge
to be reintroduced later without the review this guard exists to
force (#422 review comment).

Make the check bidirectional: an ALLOWLIST entry with no matching
edge now fails too, naming itself as stale.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
check() now dedupes enforced edges via a BTreeSet so a first-party
crate declared under both a normal and build dependency no longer
reports the same violation twice. affected::load_graph,
crate_edges::load_edges, and manifest::load_metadata all duplicated
the same cargo metadata subprocess/error-handling boilerplate; that
now lives once in paths::run_cargo_metadata.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The guard is narrowly scoped, bidirectional, comprehensively tested, and correctly integrated into CI.

Review effort: Balanced
Findings: None

Resolved since last review (1)

@jussielo-amd
jussielo-amd marked this pull request as ready for review September 22, 2026 12:09
@jussielo-amd
jussielo-amd requested a review from a team as a code owner September 22, 2026 12:09
@rominf

rominf commented Sep 22, 2026

Copy link
Copy Markdown
Collaborator

Reviewed this at 0acf9d08. Nothing blocking — it looks safe to approve after final validation (CI plus a maintainer's own pass; this reflects what a diff-level read can see, not runtime behavior).

A few things I checked specifically rather than taking on trust:

The allowlist is an exact match for the real graph. I derived the first-party edge set independently from cargo metadata --format-version 1 --locked --no-deps and compared it against ALLOWLIST: 25 enforced edges, matching entry for entry, no gaps and no stale rows. The single dev-dependency edge (rocm-dash-daemon -> rocm-core) is correctly excluded, and no workspace member currently declares a target-gated or out-of-workspace path dependency — so path.is_some() is a sound first-party test here today.

The CI gate covers the change that would actually introduce a bad edge. This was my main worry: adding a dependency touches only a Cargo.toml, so if the rust path filter were **/*.rs-only, the guard would be skipped by the exact change it exists to catch. It isn't — the filter includes **/Cargo.toml and Cargo.lock, so a manifest-only PR still runs the step. Worth remembering if that filter is ever narrowed.

The "can't allowlist your way out" test really does run on the PR that would do it. allowlist_never_contains_a_named_invariant_violation is the only thing stopping someone from resolving a red run by pasting the forbidden edge straight into ALLOWLIST — run() itself doesn't check that. It holds up: editing crate_edges.rs makes cargo xtask affected select xtask, so the test lands in the PR's nextest subset. It does mean that particular protection lives in the test suite rather than in the command wired into the clippy job. That's a reasonable split, just worth knowing it's load-bearing.

Copilot's stale-entry point is genuinely closed at head, not just claimed — check() now walks both directions and stale_allowlist_entry_fails covers it.

Two non-blocking notes:

  • The PR description still describes the check as failing "when an edge outside it appears". That was accurate before 9d31d2e5 but now undersells it: the check also fails on a removed dependency whose allowlist entry lingers. Worth a line in the body, since that's the behavior a contributor will most likely hit first, when they delete a dependency and CI stops them.
  • Deferring the AGENTS.md write-up to EAI-8045 seems right for scope. Separately from this PR: §6's "Current workspace members" list is itself out of date — it names only apps/rocm, apps/rocmd, crates/rocm-core, crates/rocm-engine-protocol and the two engine crates, omitting rocm-deps, the four rocm-dash-* crates, e2e-report, xtask and e2e-cucumber. Whoever picks up the doc work may want to correct that at the same time.

@rominf rominf left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving on the strength of the review in #422 (comment) — nothing blocking found.

To be explicit about what this covers: it reflects a diff-level read of the change plus a few targeted checks I ran myself (deriving the first-party edge set from cargo metadata and confirming it matches ALLOWLIST exactly, confirming the rust path filter includes **/Cargo.toml so a manifest-only PR can't slip past the guard, and confirming the anti-allowlist-abuse test is actually selected by cargo xtask affected). It is not a substitute for CI, which was already green at this commit, and I did not run the test suite locally.

The two notes in that comment are non-blocking and don't need to hold up the merge.

@jussielo-amd

Copy link
Copy Markdown
Collaborator Author

Thanks for the thorough re-derivation and verification — good catches on both notes.

  • Updated the Summary bullet to reflect that the check is bidirectional (catches a stale allowlist entry too, not just a new undeclared edge), so that's no longer undersold.
  • The out-of-date §6 "Current workspace members" list in AGENTS.md is covered — already being fixed in a separate, in-progress change.

@jussielo-amd
jussielo-amd added this pull request to the merge queue Sep 22, 2026
Merged via the queue into main with commit 99e3bd5 Sep 22, 2026
21 checks passed
@jussielo-amd
jussielo-amd deleted the worktree-eai-7199-crate-edge-guard branch September 22, 2026 13:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants